Name

upsf95 - X11 based Fortran 95 debugger

Overview

Upsf95 is the Fortran 90/95 debugger for use with the NAGWare f95 compiler. It is a debugger with a graphical user interface, and is a modified version of the open-source debugger ``ups'' (see http://ups.sourceforge.net/main.html for more details).

The program to be debugged should be compiled and linked with the -g option.

Upsf95 runs in its own window, thus not interfering with the user program's I/O. The upsf95 window has two major areas - one showing a structured document representing the state, the other showing the source that is being executed.

Upsf95 needs little documentation for normal use, as its interface is very straightforward. While stepping through the program, the next source line to be executed is shown highlighted in the source code window, and breakpoints are shown interspersed as pseudo-code.

Upsf95 contains the same support for debugging C code as the original ups debugger.

Usage

upsf95 executable-file [core-file|process-id] [-a user-args]

Arguments

executable-file

This is the executable file for the program to be debugged, e.g. ``a.out''. This argument is required.

core-file

This optional argument is a core dump to examine, e.g. ``core''.

process-id

This optional argument indicates an existing process to which to attach upsf95, e.g. ``1077''. The process must already be executing the program to be debugged.

-a user-args

This optional pair of arguments is for passing command-line arguments to the program being debugged, e.g. ``-a arg''. To pass more than one argument, double quotes should be used, e.g. ``-a "arg1 arg2"''. The arguments may be changed from within upsf95, by editing the command line (shown near the top of the upper window); clicking the middle mouse button on this line will edit it.

Example Debugging Session

This section contains a simple example of the use of upsf95 on a small sample Fortran program.

    MODULE fh4
      REAL :: r = -HUGE(0.0)
    END MODULE fh4

    PROGRAM fh4_prog
      USE fh4
      COMMON/fh4com/i
      CALL sub(2)
      PRINT *,i,r
    END PROGRAM fh4_prog

    SUBROUTINE sub(j)
      USE fh4
      COMMON/fh4com/i
      r = 0.5*j
      i = j*3
    END SUBROUTINE sub

Assuming the above code is in the file ``sample.f90'', it may be debugged as follows:

• Compile and link the code with the -g option to f95.
• Give the command ``upsf95 a.out'' (or whatever you called the object file).

  Upsf95 will create a separate window for debugging, divided into two main subwindows and a number of boxes. The top region is the ``display area'', and contains captions like:

  Target a.out
  	a.out
  Signals
  Environment
  Untyped variables
  Source files
  Functions
  Breakpoints
  

  The beginning of the main program will be displayed in the lower region.

• Move the mouse cursor into the upper region and left-click on ``Breakpoints''. This will invert ``Breakpoints'' to indicate that it is selected, and a menu appears near the top of the window with the captions ``Add new'', ``Remove all'', ``Restore'', and ``Load file''.

  All the objects in the display area (except ``Functions'') can be selected like this and have their own menus.

• Now left-click the ``Add new'' menu item. This causes a line to appear below the ``Breakpoints'' caption that looks like:

  Function:				active
  

  with the cursor positioned immediately after ``Function:''.
• Type ``main'', and end with the Return or Escape key. The text

     #stop;
  

  will appear at the start of the main program in the source region.

  Upsf95 represents breakpoints as this fragment of pseudo-code. You can also add breakpoints by right-clicking on the target line in the source region (see later).

• The menu just below the display area controls execution of the program being debugged. ``Start'' begins execution, ``Step'' and ``Next'' step execution over single lines of code (``Step'' steps into procedure calls, ``Next'' doesn't). ``Cont'' continues execution until it hits a breakpoint or exits. ``Stop'' stops a running program, queues a request to terminate a symbol search, or breaks out of a ``Step'' that takes a long time, ``Attach'' prompts for a PID of a target process to attach to, and ``Detach'' detaches from an attached process. ``Kill'' kills off the target process, ready for another run using ``Start''.

  To run the program, left-click on ``Start''. It will start and almost immediately hit the breakpoint you just set. You should see the first line of code in main highlighted. This means that execution has stopped just before this line. If you look at the display area you will also see that a new line has appeared under the ``Functions'' object. This should look like:

  main					sample.f90:5
  

  This shows that you are stopped at line 5 of sample.f90 in function main.

  At this point you are in the usual state for upsf95: you have the target stopped, with the line that is about to be executed highlighted in the source window and your current position in the source file shown under the ``Functions'' object in the display area.

• Click on ``Step'' in the target control menu.

  The source display will highlight each line as you step through it (some lines take several steps to complete). Click on ``Step'' several times until you step into the subroutine sub; the source display now switches to subroutine sub, which you have just stepped into. You will also see an extra line under ``Functions'' - the display should look like:

  main				sample.f90:8
  sub				sample.f90:15
  

  As you can see this is a stack trace, showing you which function called which starting from main and working down to the function you are currently stopped in.

• In the source region move the mouse over the ``j'' at the end of the highlighted line and click the left mouse button.

  You should see a line added to the stack trace, making it look like:

  main				sample.f90:8
  sub				sample.f90:15
     Integer :: J                     2
  

  This is showing that j is a variable of type INTEGER with the value 2.

  Any variable that is visible in the source window can thus have its type and value displayed by clicking on its name. (A variable that is not visible in the source window can be displayed by selecting (left-clicking on) the procedure in which it occurs in the ``Functions'' list, and using the ``Add expr'' button in the top menu.)

  Now left-click on ``r'' at the beginning of the source line. You should see a line added above the stack trace, which looks like:

     Real :: R                        -3.402823466E+38
  

  Because r is a module variable, it is not part of any single procedure and so not stored on the stack.

• Click on ``Step'' in the target control menu.

  The display for variable r is highlighted, and the value changes to half that of j, i.e.

     Real :: R                        1.000000000
  

  Displayed variables remain in the display area as you step through the program code so you can watch the values change.
• Now, step the program until it reaches the PRINT statement in the main program. Middle-click on the value for r; this will allow you to edit its value. Press Control-U to delete the current value, type ``37'' and press Return. This will set r to the value 37.
• Left-click on ``Cont'' again.

  The target continues to completion and exits. The value printed for r in the original window will be 37. The stack trace and variables disappear from the display area, and all the target control menu captions except for ``Start'' are greyed out to indicate that they are unavailable while the target is stopped.

  Another way of setting breakpoints is to use the source display. Simply scroll the source display to the required source line and right-click.

  If instead of right-clicking you press and hold the right mouse button you will see a popup menu with the captions ``Add breakpoint'', ``Execute to here'', ``Jump to here'', and ``Edit source''. You will also have seen an arrow to the left of the menu pointing at the source line you pressed the mouse over.

  The default selection is ``Add breakpoint'', so a simple right-click will add a breakpoint immediately before the source line. When a breakpoint is added the text #stop; appears in the place where the breakpoint will occur.

  This is the simplest and most common way of adding breakpoints in upsf95. The normal sequence of actions is:

  • Type the name of the function you are interested in (or enough of it to uniquely identify it) and hit ESC (the escape key). The source of the function is displayed in the source window.
  • Scroll the source to make visible the line where you want to add a breakpoint.
  • Add a breakpoint by clicking the right mouse button over the source line.

  Editable Fields

  All editable fields in upsf95 work in the same way. To start editing you click the middle mouse button over the editable text. A black ``marker bar'' appears - characters that you type appear to the left of this marker bar. You can reposition the marker bar by clicking in the new position with the middle mouse button, or by using one of the cursor movement key sequences described below.

  Clicking the left or right button confirms the edit. Clicking the middle mouse button outside the editable text area also confirms the edit. In both cases the mouse click is then interpreted as normal - this means that to confirm an edit you can simply move on to another activity. The final way to confirm an edit is to type ESC (the escape key) or click the left mouse button on the Enter Button (the small region to the right of the typing line with the "<<" image).

  To paste the current window system cut buffer, use Control-Y or click the middle mouse button on the Enter Button.

  When you try to confirm an edit, upsf95 checks that the new field value is reasonable. If not you get an error message and you are left in the edit. An immediate second attempt to quit abandons the edit and restores the original field value.

  When editing, upsf95 uses similar command keys to emacs. These key bindings are:

  Control-A	Move to start of line
  Control-B, LEFT	Move backwards one character
  Control-C	Cancel edit (not an emacs binding)
  Control-D	Delete character forwards
  Control-E	Move to end of line
  Control-F, RIGHT	Move forward one character
  Control-K	Delete to end of line
  Control-N, DOWN	Move down a line, if possible, otherwise retrieve the next later item in the history buffer
  Control-P, UP	Move up a line, if possible, otherwise retrieve the next previous item in the history buffer
  Control-U	Delete to start of line (not an emacs binding)
  Control-W	Delete text between mark and point
  Control-Y	Paste X selection
  Alt-@, Alt-space	Set mark
  Alt-B	Move backwards one word
  Alt-D	Delete word forwards
  Alt-F	Move forward one word
  Alt-M	Move to first non-whitespace character
  Alt-Delete	Delete word backwards
  Delete	Delete character backwards
  Escape	Finish edit
  Return	In an editable field, finish the edit. In the source window, start a new line.
  Alt->	Move to end of buffer
  Alt-<	Move to start of buffer

  If you run upsf95 from a terminal (or a terminal emulator like xterm), it tries to discover what keys you are using for delete and line erase. If this fails it takes both ^H (backspace) and DEL to mean delete, and ^U to mean line erase.

  Edit History

  Most of the editable fields in upsf95 have their own history of recently typed commands. For example, there is a history of typing line commands, a history of breakpoint code entered, and a history of variable values changed.

  Pressing the Left mouse button on the History Button, the small region to the right of the typing line with the triangular image, pops up a menu of recently entered data for that field.

  When editing most single line fields, a Control-P, or up arrow moves the history pointer back one entry and replaces the current text with the previous entry. Typing a Control-N, or down arrow, moves the history pointer forward one entry.

  Edit histories are saved between sessions of upsf95 in ups-state/editHistory, if you use the ups-state feature, or in the file ~/.upsEditHistory if not.

  Cut and Paste

  Text can be selected by holding the left mouse button down and moving the cursor. Selected text will be highlighted. Releasing the button sets the selection.

  Selected text can be pasted into an edit with Control-Y or by clicking the middle mouse button on the Enter Button (the small region to the right of the typing line with the ``<<'' image).

  Note that in the source window, left-clicking on a variable name (without dragging) adds the variable name to the stack frame display; only if the mouse is moved is the text made into a plain X selection (and not added to the stack frame display unless the Shift key was also being held down).

  Signals

  When the target gets a signal control returns to upsf95. Depending on the signal and the way you have specified it should be handled, the target is either stopped or restarted (possibly with a display refresh), and the signal can either be passed on to the target or ignored. Signal handling can be controlled using the ``Signals'' object in the display area.

  X11 Command Line Arguments

  Upsf95 recognises many common X11 command line arguments. These include:

  -display displayname

  Create a window on the named display rather than using the value of the DISPLAY environment variable.

  -bg colourspec

  Use colourspec as the background colour.

  -geometry geometry

  Use the specified X geometry for the window.

  -fg colourspec

  Use colourspec as the foreground colour.

  -fn fontname

  Use font fontname instead of the default.

  -iconic

  Start up as an icon rather than as a window.

  -name name

  Use name rather than the default upsf95 as the window and icon name. This name is also used when fetching X defaults.

  X11 Resources

  The appearance of upsf95 is controlled by the use of X11 resources with the prefix ``upsf95'', or if that is not found, ``Ups''. The default appearance if no resource is found is taken from the file ``Ups'' in the NAGWare f95 compiler library directory. See the ups documentation for a full list of recognised X11 resources.

  See Also

  f95(1), ups(1).

  Bugs

  Please report any bugs found to ``support@nag.co.uk'' or ``infodesk@nag.com'', along with any suggestions for improvements.